package com.example.dao;

import com.example.entity.UserInfo;
import com.example.vo.UserInfoVo;
import org.apache.ibatis.annotations.Param;
import org.springframework.stereotype.Repository;
import tk.mybatis.mapper.common.Mapper;

import java.util.List;

/**
 * 用户信息数据访问层接口
 * 主要职责：
 * 1. 管理用户账户信息（含基础信息/认证信息/状态管理等）
 * 2. 提供用户检索与统计能力
 * 3. 实现账号唯一性校验等安全相关操作
 */
@Repository
public interface UserInfoDao extends Mapper<UserInfo> {

    /**
     * 条件查询用户列表（支持用户名模糊搜索）
     *
     * @param name 查询条件：
     *             - 模糊匹配用户名（name字段，LIKE %value% 查询）
     *             - 传 "all" 时查询全部记录
     * @return {@link List<UserInfoVo>} 用户信息视图对象列表（包含部门/角色等关联信息）
     *
     * @implNote 对应XML中的<select id="findByName">实现，默认按用户ID升序排列
     */
    List<UserInfoVo> findByName(@Param("name") String name);

    /**
     * 字段唯一性校验（用于注册/编辑场景的账号唯一性验证）
     *
     * @param column 要校验的字段名
     * @param value  要校验的字段值
     * @param id     排除校验的记录ID（避免与自身重复）
     * @return int 重复记录数（0-无重复，1-已存在）
     *
     * @implNote 对应XML中的<select id="checkRepeat">实现
     * @security 注意${column}的SQL注入风险，需确保参数来源可信
     */
    int checkRepeat(@Param("column") String column,
                    @Param("value") String value,
                    @Param("id") Long id);

    /**
     * 通过用户名精确查询用户信息
     *
     * @param username 用户登录账号
     * @return {@link UserInfoVo} 用户信息视图对象
     *
     * @implNote 对应XML中的<select id="findByUsername">实现，用于登录认证场景
     */
    UserInfoVo findByUsername(String username);

    /**
     * 统计用户总数
     *
     * @return {@link Integer} 用户记录总数（包含已删除标记的记录）
     *
     * @implNote 对应XML中的<select id="count">实现
     */
    Integer count();
}